#ifndef ARAL_INTERFACE_TASK_HPP
#define ARAL_INTERFACE_TASK_HPP

#include <string>
#include <vector>
#include <functional>
#include "aral/data_structure_definition.hpp"

namespace ARAL::interface {

/**
 * @class Task
 * @brief 机器人任务管理器, 负责管理和调度一个或多个规划器(Planner)的工作流。
 * 
 * @details
 *  **核心设计: 隐式启动与同步控制**
 *  Task实例在创建后即处于活动状态，无需显式的`start`调用。其行为模式由同步指令决定：
 * 
 *  1. **默认模式 (并行独立执行)**:
 *     - 如果不调用任何同步指令，Task会以并行独立模式运行。当任何一个受其管理的Planner中被添加了运动指令(如 `addMoveLine`)，该Planner会立即独立开始规划。
 *     - 规划成功后，用户可立即通过 `tskUpdateCycle` 函数获取轨迹点。
 * 
 *  2. **同步模式 (并行同步执行)**:
 *     - 调用 `tskWaitSyncMove()`: 这会将Task置于等待状态，所有Planner的自动规划功能被暂停。
 *     - 添加运动指令: 向一个或多个由该Task管理的Planner中添加运动指令。这些指令将被缓存。
 *     - 调用 `tskSyncMoveOn()`: 这是一个触发信号，它会使所有等待中的Planner同时开始规划各自缓存的指令，从而实现“同启”运动。
 *
 *  这种设计简化了API，使得无论是简单的单机任务还是复杂的多机同步任务，都能通过统一的流程进行管理。
 */
class Task
{
protected:
    virtual ~Task() = default;

public:

    /**
     * @brief 设置任务状态(其中状态 IDEL 和 PAUSED 可由用户传入; 其他状态根据运动指令调用逻辑来决定)
     * note 如果设置为 IDEL 状态, 则清空所有规划器的轨迹执行队列; 
     *      如果设置为 PAUSED 状态, 则需要调用 tskResume 函数来恢复任务执行; 
     * @param state 任务状态
     * @return 成功返回0，失败返回错误码。
     */
    virtual int tskSetTaskState(const TaskState& state) = 0;

    /**
     * @brief 获取任务状态
     * @return 任务状态
     */
    virtual TaskState tskGetTaskState() const = 0;

    /**
     * @brief 设置任务的规划周期，与控制周期一致即可
     * @param period: 规划周期，单位:秒
     * @return 成功返回0，失败返回错误码。
     */
    virtual int tskSetCycle(const double& period) = 0;

    /**
     * @brief 获取任务的规划周期
     * @return 规划周期，单位:秒
     */
    virtual double tskGetCycle() = 0;

    /**
     * @brief 设置任务的笛卡尔空间最大规划速度  
     * @param cartesianVelLimits: 笛卡尔速度最大值
     * @param buffSize: 轨迹执行队列中需要缓冲的轨迹点数，用于对冲调用该接口需要的耗时.(如果软件已经调用tpUpdateCycle在软件层缓存轨迹点，则buffSize可置为0)
     * @return 成功返回0，失败返回错误码。
     */
    virtual int tskSetCartesianVelocityLimits(const Array2d& cartesianVelLimits, const unsigned int buffSize) = 0;

     /**
     * @brief 得到任务的笛卡尔空间最大规划速度
     * @return: 线速度(m/s)和角速度(rad/s)
     */
    virtual const Array2d tskGetCartesianVelocityLimits()const = 0;

    /**
     * @brief 缩放任务空间的最大规划速度
     * @param velScal: 速度调整比例应大于0.01, 一般不大于1
     * @param buffSize: 轨迹执行队列中需要缓冲的轨迹点数，用于对冲调用该接口需要的耗时.(如果软件已经调用tpUpdateCycle在软件层缓存轨迹点，则buffSize可置为0)
     * @return 成功返回0，失败返回错误码。
     */
    virtual int tskSetVelocityScaleFactor(const double& velScal, const unsigned int buffSize) = 0;

     /**
     * @brief 获得任务中速度缩减比例参数
     * @return 速度比例参数
     */
    virtual double tskGetVelocityScaledFactor() = 0;

    /**
     * @brief 获得任务中剩余的轨迹段运动总时长
     * @return 剩余的轨迹段运动总时长, 单位:秒
     */
    virtual double tskGetLeftMoveDuration() = 0;
    
    /**
     * @brief [同步指令] 触发所有等待中的规划器同时开始规划。
     * @details 这是多机/多任务同步流程的触发点。调用此函数后，所有在此Task管理下、且因 `tskWaitSyncMove` 而暂停的Planner将同时开始处理它们各自的指令队列。
     *          这确保了多个独立的运动任务能够“同启”。
     * @see tskWaitSyncMove
     * @return 成功返回0，失败返回错误码。
     */
    virtual int tskSyncMoveOn() = 0;

    /**
     * @brief [同步指令] 使任务进入等待状态，准备进行同步规划。
     * @details 调用此函数后，此Task管理下的所有Planner将不会自动开始规划，即使向它们添加了新的运动指令。
     *          它们会一直等待，直到用户调用 `tskSyncMoveOn()`。
     *          这通常是定义一个同步运动块的起点。
     * @see tskWaitSyncMove
     * @return 成功返回0，失败返回错误码。
     */
    virtual int tskWaitSyncMove() = 0;

    /**
     * @brief 按照指定的周期更新规划器的状态, 并输出对应的轨迹点信息。
     *        对于多机器人任务，将根据机器人数量N，一次性生成N个轨迹点。
     * @param cycle 轨迹点的更新步长，单位:秒
     * @param point 输出的轨迹点。对于单机器人任务，`point`中只包含一个元素；对于多机器人任务，`point`将包含N个`TrajectoryPoint`元素，分别对应N个机器人的轨迹点。
     * @param failed_planner 输出参数。当函数返回错误码（< 0）时，该参数会返回导致错误的规划器句柄。
     * @return 返回值 < 0, 表示没有正确输出轨迹点; = 0 表示正常输出; = 40001 表示取到路径的第一个点;
     *         = 40002 表示取到路径最后一点，该段路径运动结束; = 40003 表示轨迹队列为空运动结束或者规划器处于暂停状态（point不更新）
     */
    virtual int tskUpdateCycle(const double& cycle, std::vector<TrajectoryPoint>& point, PlannerHandle& failed_planner) = 0;

    /**
     * @brief 算法会根据当前轨迹执行队列的状态规划减速速度轮廓，并终止轨迹段的执行, (当调用紧急停止时, 机械臂会在关节空间减速, 不能保证停在原来的路径上)
     * @param type: 减速类型,具体参考StopType枚举
     * @param acc_ratio: 加速度比例参数, 基准为根据 tpSetVelocityAndAccelerationLimits 设置的加速度参数
     * @param buffSize: 减速时缓冲区的大小, 如果软件内部有缓冲处理, 可以将该参数置零(建议在软件内部通过调用tpUpdateCycle函数来缓冲数据点)
     * @return: 返回值 < 0 表示状态切换失败
     */
    virtual int tskStop(const StopType& type, const double& acc_ratio, const unsigned int buffSize) = 0;

    /**
     * @brief 从暂停态恢复到执行态, 并接着执行未完成的轨迹段
     * @return 成功返回0，失败返回错误码。
     */
    virtual int tskResume() = 0;
};//class Task  
typedef std::shared_ptr<Task> TaskPtr;
}   //namespace ARAL::interface

#endif // ARAL_INTERFACE_TASK_HPP